What This Module Does.

An overview of the html module's role and abilities.

@h Prerequisites.
The html module is a part of the Inform compiler toolset. It is
presented as a literate program or "web". Before diving in:
(a) It helps to have some experience of reading webs: see //inweb// for more.
(b) The module is written in C, in fact ANSI C99, but this is disguised by the
fact that it uses some extension syntaxes provided by the //inweb// literate
programming tool, making it a dialect of C called InC. See //inweb// for
full details, but essentially: it's C without predeclarations or header files,
and where functions have names like |Tags::add_by_name| rather than |add_by_name|.
(c) This module uses other modules drawn from the compiler (see //structure//), and also
uses a module of utility functions called //foundation//.
For more, see //foundation: A Brief Guide to Foundation//.

@h Purpose.
Many functions of the Inform toolset involve the generation of HTML in some
way, but almost all of that work is actually done by the //foundation// module.
If you're interested in how HTML pages are made, how tags are opened and closed,
and such, see //foundation: HTML// and //foundation: Epub Ebooks//. All of that
code is general-purpose.

By contrast, the //html// module is very much a part of the Inform compiler
and provides highly Inform-specific functions needed to make the intranet-like
miniature websites it generates on the fly -- problem pages, the Index, the
extensions documentation. In particular, it offers:

(a) clickable links to positions in source text, opening the Source panel
in the Inform GUI apps as needed -- see //SourceLinks::link//;
(b) paste buttons which, when clicked, insert text into the Source panel,
or which open certain files or folders -- see //Paste Buttons//;

@h Custom HTML link protocols.
This seems a useful place to document something which the Inform GUI apps
must provide. These render index, problem and extension mini-website pages
in embedded web browser views: for example, Inform on MacOS is essentially
running a copy of Safari (or rather, its underlying engine WebKit) under
the hood to display these. The material displayed consists of standard web
pages, except that there are two custom "transport protocols" or "URL schemas".

Protocols like this go under a number of names, partly because there are many
subtly different ideas here which only experts can distinguish (see
//https://en.wikipedia.org/wiki/Application_layer// for the entrance to the
rabbit-hole). To us, anyway, protocols are the prefixes of URLs which end
with a colon -- all browsers recognise a standard set of these, of which |http:|
|https:| and |file:| are by far the most commonly used.

Inform uses two non-standard ones in these internal pages, and so the GUI app
must implement them for its embedded web engine:
(a) |source:| is used in link |href|s to make source text references -- see //Source Links//;
(b) |inform:| is used both for links to internal or external pages generated
by Inform, and also for image |src|s. It behaves just like |http:|, except
that it derives the location of a file from the given URL in a different way.

@ The reason |inform:| is needed is that HTML files generated by Inform have
no way to know the relative URLs necessary to access e.g. icon images for
the World index, which will be in different places in the file system on
different Inform apps. More formally, the specification of |inform:| is that --

(a) |inform://...| is interpreted as a reference to one of the built-in images,
i.e., to wherever the app has internally stashed the Inform distribution's
directory |resources/Imagery|. Barring errors in Inform, or in the app, this
should never 404.

(b) For any path |*|, |inform://Extensions/*| should be fetched as |*| in the
external resources area -- that is, the place to which the app is installing
new extensions. If no file was found, the link should simply do nothing:
the application is required not to produce a 404 error page, or to
blank out the page currently showing.

@h Localisation.
This module also contains a very simple system for "localisation" of text,
that is, enabling the user to output text in multiple human languages. (Inform
makes heavy use of this in the Index.) This may not appear at first to have
anything to do with HTML, but in fact we will mainly use it when generating
web pages in the Index, so it has some conveniences for stylistic markup as well.

See //Localisation// for details.
